home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / tosfixes / enhancer.lzh / ENHANCER / NEW_FUNC.TXT < prev   
Text File  |  1993-06-21  |  14KB  |  357 lines
  1.                            Enhanced NVDI 2.50 Functions
  2.                            ============================
  3.  
  4.    This document describes the enhanced NVDI 2.50 functions for screen 
  5.    output.
  6.  
  7. 1. Off-Screen Bitmaps
  8. =====================
  9.  
  10.    Sometimes  it's  very  useful  to  perform  drawing operations on hidden 
  11.    screens   and  to  use vro_cpyfm() to transfer the complete image to the 
  12.    screen  - you may want to avoid screen flickering or just cache a screen 
  13.    region, etc.. These hidden screens are called `Off-Screen Bitmaps'.
  14.    You can create off-screen bitmaps by calling OPEN BITMAP. You can either 
  15.    pass  the  size  of a bitmap to v_opnbm() which will allocate memory for 
  16.    it,  or  you  can  pass a pointer to a bitmap you have already allocated 
  17.    memory  for. The bitmap will be in device-specific or monochrome format. 
  18.    Therefore  you  can  copy  raster areas from screen to a bitmap and vice 
  19.    versa without using vr_trnfm(). 
  20.    The function CLOSE BITMAP closes a bitmap created with OPEN BITMAP and - 
  21.    if necessary - frees the memory block.
  22.  
  23.  
  24.       OPEN BITMAP (VDI 100, 1)
  25.  
  26.       void  v_opnbm( WORD *work_in, MFDB *bitmap, WORD *handle, WORD *work_out )
  27.       {
  28.          pb[1] = work_in;
  29.          pb[3] = work_out;
  30.          pb[4] = work_out + 45;
  31.  
  32.          contrl[0] = 100;
  33.          contrl[1] = 0;
  34.          contrl[3] = 20;
  35.          contrl[5] = 1;
  36.          *(MFDB *)&contrl[7] = bitmap;
  37.  
  38.          vdi();
  39.  
  40.          *handle = contrl[6];
  41.          pb[1] = intin;
  42.          pb[3] = intout;
  43.          pb[4] = ptsout;
  44.       }
  45.  
  46.       VDI arrays:
  47.  
  48.        Element          | Content
  49.       ------------------|-------------------------------------------
  50.       contrl[0]         | 100    opcode for v_opnbm()
  51.       contrl[1]         | 0      number of parameters in ptsin
  52.       contrl[2]         | 6      number of parameters in ptsout
  53.       contrl[3]         | 20     number of parameters in intin
  54.       contrl[4]         | 45     number of parameters in intout
  55.       contrl[5]         | 1      sub-opcode for v_opnbm()
  56.       contrl[6]         | handle
  57.       contrl[7..8]      | bitmap pointer to the MFDB of bitmap
  58.                         |
  59.       intin[0..19]      | work_in[0..19]
  60.                         |
  61.       intout[0..44]     | work_out[0..44]
  62.                         |
  63.       ptsout[0..11]     | work_out[45..56]
  64.  
  65.  
  66.       handle:           graf_handle()
  67.  
  68.       work_in[0..10]:   see v_opnwk()/v_opnvwk()
  69.       work_in[0]:       Getrez() + 2
  70.       work_in[11]:      Width -1 (e.g. 1279)
  71.       work_in[12]:      Height -1 (e.g. 959)
  72.       work_in[13]:      Width of a pixel in 1/1000 mm
  73.       work_in[14]:      Height of a pixel in 1/1000 mm
  74.       work_in[15..19]:  reserved, should contain 0
  75.  
  76.       Attention:  Work_in[11]  +  1  should  be  divisible  by  16  without 
  77.                   remainder.  Otherwise  the  VDI  driver  will  round  up  
  78.                   (work_in[11] + 1) to the next number which can be divided 
  79.                   by 16 without remainder.
  80.                   If  pixel  width  and  height are 0 the pixel size of the 
  81.                   screen workstation is used.
  82.  
  83.       work_out[0..1]:   see v_opnwk()/v_opnvwk()
  84.       work_out[2]:      0
  85.       work_out[3..38]:  see v_opnwk()/v_opnvwk()
  86.       work_out[39]      0 (no hardware clut)
  87.       work_out[39..56]: see v_opnwk()/v_opnvwk()
  88.  
  89.       bitmap:           pointer to MFDB
  90.  
  91.       If  bitmap->fd_addr  is  zero,  the  VDI will allocate memory for the 
  92.       bitmap and will clear it (in contrast to v_opnvwk() ). 
  93.  
  94.       To  open a bitmap in device-specific format bitmap->fd_nplanes should 
  95.       be  zero  or  the  number  of  planes of the screen (work_out[4] from 
  96.       vq_extnd()).  If bitmap->fd_nplanes is 1, a monochrome bitmap will be 
  97.       created.
  98.       The   elements   of  the  MFDB  (fd_addr,  fd_w,  fd_h,  fd_wdwidth,  
  99.       fd_stand,fd_nplanes)  are  set  by  the  VDI  before  returning  from 
  100.       v_opnbm().  If  there  is  not  enough  memory to create a bitmap the 
  101.       handle will be zero and the MFDB will not be changed.
  102.  
  103.       If  bitmap->fd_addr  is  not  zero,  it  will be used as pointer to a 
  104.       bitmap.  If  the bitmap is in standard format, it will be transformed 
  105.       into device-specific format. If the number of planes of the bitmap is 
  106.       not supported by the VDI, a zero handle will be returned.
  107.  
  108.  
  109.       CLOSE BITMAP (VDI 101, 1)
  110.  
  111.       void  v_clsbm( WORD handle )
  112.       {
  113.          contrl[0] = 101;
  114.          contrl[1] = 0;
  115.          contrl[3] = 0;
  116.          contrl[5] = 1;
  117.          contrl[6] = handle;
  118.          vdi();
  119.       }
  120.  
  121.       VDI arrays:
  122.  
  123.        Element          | Content
  124.       ------------------|-------------------------------------------
  125.       contrl[0]         | 101    opcode for v_clsbm()
  126.       contrl[1]         | 0      number of parameter in ptsin
  127.       contrl[2]         | 0      number of parameter in ptsout
  128.       contrl[3]         | 0      number of parameter in intin
  129.       contrl[4]         | 0      number of parameter in intout
  130.       contrl[5]         | 1      sub-opcode for v_clsbm()
  131.       contrl[6]         | handle
  132.  
  133.       The  function  v_clsbm() closes the bitmap specified with handle. The 
  134.       memory of the bitmap will be freed if the VDI has allocated it.
  135.  
  136.  
  137.    Raster Operations and Off-Screen Bitmaps:
  138.    =========================================
  139.  
  140.    Raster  operations between screen and a bitmap generally have to be done 
  141.    in device-specific format.
  142.    If a bitmap is the destination of a raster operation, you should use the 
  143.    bitmap's  handle.  Otherwise  vro_cpyfm() or vrt_cpyfm() cannot clip the 
  144.    area they have to copy and may overwrite other applications' memory.
  145.  
  146.    If  you  use  the  handle  of a bitmap created by v_opnbm() for a raster 
  147.    operation  then  a  zero in MFDB->fd_addr is not a pointer to the screen 
  148.    but to the bitmap.
  149.    In  contrast  to  a screen workstation on a bitmap clipping is also done 
  150.    when  MFDB->fd_addr  is  the address of the bitmap returned by v_opnbm() 
  151.    (on  a  screen  workstation  clipping is only done when MFDB->fd_addr is 
  152.    zero).
  153.  
  154.    See also: BITMAP.C
  155.  
  156.    ESCAPES
  157.    -------
  158.    VDI  escape functions can't be used on Off-Screen bitmaps. The calls are 
  159.    ignored.
  160.  
  161.    vs_color()/vq_color()
  162.    ---------------------
  163.    vs_color()  and  vq_color()  can  be used in Hi- or True Color mode on a 
  164.    Off-Screen  bitmap.  Otherwise the calls are ignored (vq_color() returns
  165.    -1 if not used in Hi- or True Color mode).
  166.  
  167.    vst_point()
  168.    -----------
  169.    vst_point()  and  all  other  functions  that  change the text character 
  170.    height  in  printer points won't set the requested character size if the 
  171.    pixel  height  and  width of the screen is different to the pixel height 
  172.    and width of the Off-Screen bitmap.
  173.  
  174.    v_show_c()/v_hide_c()
  175.    ---------------------
  176.    v_show_c() and v_hide_c() can't be used on Off-Screen bitmaps. The calls 
  177.    are ignored.
  178.  
  179.  
  180. 2. vq_scrninfo()
  181. ================
  182.  
  183.    The  funcion  INQUIRE  SCREEN INFORMATION returns additional information 
  184.    about the device-specific screen format.  
  185.    This function is useful for programs which
  186.    -  support Genlock (Overlay)
  187.    -  build  rasters  (also  in  TrueColor)  and  want  to  copy them with 
  188.       vro_cpyfm() to the screen
  189.    -  save rasters (e.g. XIMGs)
  190.  
  191.       VQ_SCRNINFO( 102, 1 )
  192.  
  193.       void  vq_scrninfo( WORD handle, WORD *work_out )
  194.       {
  195.          pb[3] = work_out;
  196.  
  197.          intin[0] = 2;
  198.          contrl[0] = 102;
  199.          contrl[1] = 0;
  200.          contrl[3] = 1;
  201.          contrl[5] = 1;
  202.          contrl[6] = handle;
  203.          
  204.          vdi();
  205.  
  206.          pb[3] = intout;
  207.       }
  208.  
  209.       VDI arrays:
  210.  
  211.        Element          | Content
  212.       ------------------|-------------------------------------------
  213.       contrl[0]         | 102    opcode for vq_scrninfo()
  214.       contrl[1]         | 0      number of parameters in ptsin
  215.       contrl[2]         | 0      number of parameters in ptsout
  216.       contrl[3]         | 1